package com.smart.community.property.service;

import com.smart.community.commons.result.Result;

import java.math.BigDecimal;
import java.util.Map;

/**
 * 物业公司统计服务接口
 * 提供物业公司相关的数据统计功能
 * 
 * @author Wu.Liang
 * @since 2025-01-30
 */
public interface IPropertyCompanyStatisticsService {
    
    /**
     * 获取物业公司总服务面积
     * 根据物业公司ID，获取下属所有社区→楼栋→单元→房户的面积总和
     * 
     * @param propertyCompanyId 物业公司ID
     * @return 总服务面积（平方米）
     * @throws Exception 统一异常
     */
    Result<BigDecimal> getTotalServiceArea(Long propertyCompanyId) throws Exception;
    
    /**
     * 获取物业公司服务社区数量
     * 根据物业公司ID，获取下属所有社区数量
     * 
     * @param propertyCompanyId 物业公司ID
     * @return 服务社区数量
     * @throws Exception 统一异常
     */
    Result<Long> getServiceCommunityCount(Long propertyCompanyId) throws Exception;
    
    /**
     * 获取物业公司服务户数
     * 根据物业公司ID，获取下属所有社区→楼栋→单元→房户的数量
     * 
     * @param propertyCompanyId 物业公司ID
     * @return 服务户数
     * @throws Exception 统一异常
     */
    Result<Long> getServiceHouseholdCount(Long propertyCompanyId) throws Exception;
    
    /**
     * 获取物业公司综合统计信息
     * 一次性获取所有统计数据的聚合接口，提高性能
     * 
     * @param propertyCompanyId 物业公司ID
     * @return 综合统计信息
     * @throws Exception 统一异常
     */
    Result<Map<String, Object>> getComprehensiveStatistics(Long propertyCompanyId) throws Exception;
    
    /**
     * 刷新物业公司统计缓存
     * 当相关数据发生变化时，用于刷新缓存
     * 
     * @param propertyCompanyId 物业公司ID
     * @return 是否成功
     * @throws Exception 统一异常
     */
    Result<Boolean> refreshStatisticsCache(Long propertyCompanyId) throws Exception;
}
